How to diagnose errors in `.htaccess`?

Diagnosing errors in `.htaccess` files can be a meticulous process, but it is critical for maintaining the functionality and security of your web server, particularly if you are using Apache. Below is a step-by-step guide to help you identify and rectify errors in `.htaccess` files, supplemented with examples and reliable sources.

1. Enable Apache’s Mod\_rewrite and Error Logging

Before diving into diagnosing `.htaccess` errors, ensure that the `mod_rewrite` module is enabled and that error logging is set up correctly.

Mod\_rewrite can be enabled in the Apache configuration file (`httpd.conf` or `apache2.conf`) by adding or uncommenting the following line:
```
LoadModule rewrite_module modules/mod_rewrite.so
```

2. Locate Error Logs

The Apache error log is invaluable for troubleshooting. The location of the log file can be specified in Apache’s configuration file. Common locations include `/var/log/apache2/error.log` for Unix-based systems and `C:\Apache24\logs\error.log` for Windows.

Check the error log immediately after encountering an issue. Typical log entries might look like this:

```
[Wed Oct 11 10:32:07.123456 2023] [core:error] [pid 12345:tid 140737488:client 192.168.0.1] AH00126: Invalid command ‘RewriteEngine’, perhaps misspelled or defined by a module not included in the server configuration
```

3. Common `.htaccess` Errors and Solutions

a. Syntax Errors

A common issue is incorrect syntax. Error messages in the log can help pinpoint these errors.
Example:
```
RewriteEngine On
RewriteRule ^index\.html$ welcome.html
```
- Error Message: `Invalid command ‘Rewri’, perhaps misspelled or defined by a module not included in the server configuration`
- Solution: Ensure all commands are correctly spelled and case-sensitive.

b. Incorrect Directory Context

Ensure that `.htaccess` directives are valid for the directory context. Some directives are only allowed in the global configuration context.
Example:
```
Options +FollowSymLinks
```
- Error Message: `Options not allowed here`
- Solution: Move such directives to the main configuration file or enable permissions via `` tags.

4. Validate Regular Expressions

If you are using regular expressions in your rewrite rules or redirects, verify them with tools like regexr.com or regex101.com to ensure they behave as expected.

5. Use `RewriteLog` and `RewriteLogLevel`

While Apache 2.4 and later have deprecated `RewriteLog` and `RewriteLogLevel`, the `LogLevel` directive with the `trace` option can be used to achieve similar debugging information.

Apache 2.4 Example:
```
LogLevel alert rewrite:trace6
```

6. Test Incrementally

When modifying `.htaccess`, make small incremental changes and test after each modification. This isolatory technique helps pinpoint the exact change causing an error.

7. Use Backup and Version Control

Always keep a backup of a known good configuration of your `.htaccess` file. Using version control systems like Git can also help keep track of changes and quickly revert to a previous version if needed.

Examples:

Redirect Example
A correct redirection should look like:
```
Redirect 301 /old-page.html http://www.example.com/new-page.html
```
- Misconfiguration: `Redirect /old-page http://` lacking the 301 directive.
- Solution: Ensure the status code and the full correct URL are included.

Rewrite Example
For rewriting URLs:
```
RewriteEngine On
RewriteCond %{HTTP_HOST} ^example\.com
RewriteRule (.*) http://www.example.com/$1 [R=301,L]
```
- Common Mistake: Missing conditions or incorrect flags.
- Solution: Validate all parts of the rule and ensure flags are correct.

Reliable Sources to Consult:

1. Apache Official Documentation:
- [Apache .htaccess Tutorial](https://httpd.apache.org/docs/current/howto/htaccess.html)
- [mod_rewrite Documentation](https://httpd.apache.org/docs/current/mod/mod_rewrite.html)

1. Community and Forums:
- Stack Overflow ([.htaccess questions](https://stackoverflow.com/questions/tagged/.htaccess))
- Server Fault ([Apache questions](https://serverfault.com/questions/tagged/apache-2.2))

1. Books:
- “Apache HTTP Server 2.2 Official Documentation” by The Apache Software Foundation.
- “HTTP: The Definitive Guide” by David Gourley and Brian Totty.

Being thorough and methodical will typically lead to an effective resolution of `.htaccess` issues. Always refer to the latest and most specific documentation related to your server version.